The user report listed {{group:...}} as a missing embed with no stated
semantics. Neither the PR #159 design doc nor the codebase pinned down a
definition, so this commit picks the most useful reading:

  {{group:FIELD}} renders a count-by-value table of the named artifact
  field. Example outputs:

    {{group:status}}  →  draft / approved / shipped counts
    {{group:type}}    →  per-type counts (complement to {{stats:types}})
    {{group:asil}}    →  per-ASIL counts from a custom YAML field

Missing / empty values bucket into "unset" so the totals equal the
project artifact count. List-valued fields (e.g. tags) render as
comma-joined keys — per-tag grouping is a future enhancement.

The renderer reuses the same html_escape / embed-table class set as the
rest of the embeds, and returns an EmbedError for an empty FIELD.

Five unit tests: status grouping with an "unset" row, type grouping,
custom YAML field (asil), empty-field rejection, and empty-store
no-data path.

Implements: REQ-007
Refs: FEAT-032

The user report listed {{group:...}} as a missing embed with no stated
semantics. Neither the PR #159 design doc nor the codebase pinned down a
definition, so this commit picks the most useful reading:

  {{group:FIELD}} renders a count-by-value table of the named artifact
  field. Example outputs:

    {{group:status}}  →  draft / approved / shipped counts
    {{group:type}}    →  per-type counts (complement to {{stats:types}})
    {{group:asil}}    →  per-ASIL counts from a custom YAML field

Missing / empty values bucket into "unset" so the totals equal the
project artifact count. List-valued fields (e.g. tags) render as
comma-joined keys — per-tag grouping is a future enhancement.

The renderer reuses the same html_escape / embed-table class set as the
rest of the embeds, and returns an EmbedError for an empty FIELD.

Five unit tests: status grouping with an "unset" row, type grouping,
custom YAML field (asil), empty-field rejection, and empty-store
no-data path.

Implements: REQ-007
Refs: FEAT-032

…et docs embeds + rivet query (#180)

* fix(markdown): render mermaid fences as <pre class="mermaid">

Artifact descriptions go through rivet-core's pulldown-cmark based
render_markdown. That renderer was emitting pulldown's default
<pre><code class="language-mermaid"> for fenced mermaid blocks, which
the dashboard's mermaid.js (selector `.mermaid`) never matches — so
diagrams in artifact descriptions rendered as literal source.

Add a tiny event-mapping pass that replaces the Start/End code-block
events for `mermaid` fences with synthetic HTML wrappers (NUL-byte
sentinels that cannot appear in input, rewritten post-html-push). Other
raw HTML events are still dropped for XSS defence, and the sanitize
pass still runs. Non-mermaid fences keep their existing rendering.

Covers the bug end-to-end: markdown unit tests verify the <pre
class="mermaid"> shape and regression for rust fences; architecture.yaml
ARCH-CORE-001 now carries a mermaid diagram as a live fixture, and a
Playwright regression walks the artifact page and asserts mermaid.js
actually produces an SVG.

Fixes: REQ-032
Refs: FEAT-032

* feat(embed): {{query:(sexpr)}} renders live s-expression results

Adds a read-only {{query:(...)}} embed backed by the existing
sexpr_eval::parse_filter + matches_filter_with_store pair — the same path
that powers `rivet list --filter` and MCP's `rivet_query`. The embed
renders a compact `id | type | title | status` table, clamped to a
default of 50 rows (hard max 500 via `limit=N`), with a visible
"Showing N of M" footer on truncation so nothing disappears silently.

Parser changes:

- `EmbedRequest::parse` was previously splitting on `:` blindly, which
  corrupted any s-expression argument.  For `name == "query"` it now
  expects a balanced-paren form `{{query:(...)}}` and captures the whole
  paren group as the single positional arg.  Parens inside string
  literals are respected so `(= title "foo)bar")` parses correctly.
- All other embed shapes (`stats`, `stats:types`, `table:T:F`, …) keep
  their existing colon-split behaviour — covered by regression tests.

Tests: 12 new unit tests covering the paren scanner (simple, nested,
string-literal, unbalanced), the `query` parse shape, an end-to-end
`query_embed_matches_sexpr_filter` cross-check against the evaluator
directly, truncation, `limit=` clamping, and error propagation from a
malformed filter.

Implements: REQ-007
Refs: FEAT-032

* feat(embed): {{stats:type:NAME}} for single-type counts

{{stats:types}} already renders the full per-type count table; users
asking for a single number — e.g. "how many requirements do we have?"
— had to eyeball it out of the table. Add a granular form
{{stats:type:requirement}} that renders a one-row table with just the
count for the named type.

Unknown types render count=0 rather than erroring, matching SC-EMBED-3:
the rule is "visible output, never silent disappearance". An empty type
name falls back to an `embed-error` span.

Four unit tests: counts correctly, unknown type → zero, empty name →
visible error, and a regression check that the existing {{stats:types}}
form still produces the full multi-row table.

Implements: REQ-007
Refs: FEAT-032

* feat(embed): {{group:FIELD}} count-by-value grouping

The user report listed {{group:...}} as a missing embed with no stated
semantics. Neither the PR #159 design doc nor the codebase pinned down a
definition, so this commit picks the most useful reading:

  {{group:FIELD}} renders a count-by-value table of the named artifact
  field. Example outputs:

    {{group:status}}  →  draft / approved / shipped counts
    {{group:type}}    →  per-type counts (complement to {{stats:types}})
    {{group:asil}}    →  per-ASIL counts from a custom YAML field

Missing / empty values bucket into "unset" so the totals equal the
project artifact count. List-valued fields (e.g. tags) render as
comma-joined keys — per-tag grouping is a future enhancement.

The renderer reuses the same html_escape / embed-table class set as the
rest of the embeds, and returns an EmbedError for an empty FIELD.

Five unit tests: status grouping with an "unset" row, type grouping,
custom YAML field (asil), empty-field rejection, and empty-store
no-data path.

Implements: REQ-007
Refs: FEAT-032

* feat(cli): `rivet docs embeds` + embed registry

Adds `rivet_core::embed::EMBED_REGISTRY` — a `&[EmbedSpec]` slice with
one entry per known embed (`stats`, `coverage`, `diagnostics`, `matrix`,
`query`, `group`, plus the legacy `artifact` / `links` / `table`
inline embeds). Each spec carries the `name`, a compact `args` signature,
a one-line `summary`, a runnable `example`, and a `legacy` flag so the
inline embeds are still listed even though they dispatch from
`document.rs` rather than `resolve_embed`.

Surfaces the registry in three places so discoverability stays in sync:

- `rivet docs embeds` (and `--format json`) — prints an aligned table or
  emits a machine-readable list; usage footer points at `rivet embed`
  and `rivet docs embed-syntax`.
- Dashboard Help view — new "Document Embeds" card built from the same
  registry so users browsing at /help see the exact same set.
- Unit tests assert that every name dispatched in `resolve_embed` also
  appears in `EMBED_REGISTRY`, and that every registry example parses
  via `EmbedRequest::parse` (catches copy-paste rot).

Integration tests in `rivet-cli/tests/embeds_help.rs` walk the built
binary end-to-end for both text and JSON output.

While here, fix a latent order-dependent assertion in the earlier
`query_embed_matches_sexpr_filter` test — store iteration is not
stable, so compare as a sorted set instead.

Implements: REQ-007
Refs: FEAT-032, FEAT-001

* feat(cli): `rivet query --sexpr ...` mirrors MCP rivet_query

Lifts the shared s-expression evaluation path into
`rivet_core::query::execute_sexpr` so MCP's `rivet_query` tool, the new
`rivet query` CLI, and the `{{query:(...)}}` document embed all converge
on one function.  The result struct carries `matches`, `total`, and a
`truncated` flag so callers can render the same "Showing N of M" footer
without re-running the filter.

CLI surface:

    rivet query --sexpr '(and (= type "requirement") (has-tag "stpa"))'
    rivet query --sexpr '...' --format json    # MCP shape envelope
    rivet query --sexpr '...' --format ids     # newline-separated IDs
    rivet query --sexpr '...' --limit 25

Three output formats — text (aligned columns), json (the MCP envelope
`{filter, count, total, truncated, artifacts[]}`), and ids (for shell
pipelines: `rivet query --format ids | xargs -n1 rivet show`).

MCP's `tool_query` is refactored to use `execute_sexpr` directly and
now returns the same envelope shape (adding `total` + `truncated`
fields alongside the existing `filter`, `count`, `artifacts`), so
scripts working against MCP and CLI read identical JSON.

Five unit tests in `rivet_core::query::tests` (type filter, limit +
truncation, empty-filter-matches-all, parse-error propagation, tag
filter agreement with `rivet list --filter`).  Three integration tests
in `rivet-cli/tests/cli_commands.rs` exercise the binary end-to-end for
`--format ids` vs. `rivet list --type`, the MCP-shape JSON envelope,
and the error path for an unbalanced s-expression.

Implements: REQ-007
Refs: FEAT-010, FEAT-032